home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / qlib56.zip / GRAPHICS.DOC < prev    next >
Text File  |  1992-12-11  |  71KB  |  1,794 lines
  1.  
  2.  ************************ QLIB GRAPHICS ***********************************
  3.  
  4.   QLIB's graphics subroutines were written initially to provide Hercules
  5.   graphics functions without using QB's QBHERC.COM or MSHERC.COM memory-
  6.   resident drivers, and to provide added capabilities.  Most of these
  7.   subroutines now work in additional graphics modes.  QLIB automatically
  8.   configures itself for the graphics mode in use.
  9.  
  10.   Locations on Graphics screens are defined by coordinate pairs such as (x,y).
  11.   X-coordinates are the horizontal dimensions of the screen, and Y-coordinates
  12.   are the vertical coordinates.  X = 0 is the at the left edge of the screen,
  13.   and X = 719 is the right edge of a Hercules screen, while Y = 0 is the top
  14.   edge of the screen and Y = 347 is the bottom (Hercules).  Thus, the
  15.   coordinate (719,0) is the upper right corner of a Hercules screen.  Maximum
  16.   coordinate values for supported modes are shown on the next page.
  17.  
  18.   You may also use your own coordinate system with QLIB graphics, similar
  19.   to using WINDOW with BASIC's graphics functions.  See QWindow at the
  20.   end of this file.
  21.  
  22.  
  23.  
  24.   QLIB graphics modes are:
  25.  
  26.   Mode           Maximum x   Maximum y    Colors    Equipment
  27.  
  28.   HGraph           719          347       2         Hercules
  29.   HGraph           719          347       16        Hercules InColor
  30.   SCREEN 1         319          199       4         CGA, EGA, MCGA, VGA
  31.   SCREEN 2         639          199       2         CGA, EGA, MCGA, VGA
  32.   SCREEN 3 (1)     719          347       2         Hercules
  33.   SCREEN 4         639          399       2         ATT 6300  (5)
  34.   SCREEN 7         319          199       16        EGA, VGA
  35.   SCREEN 8         639          199       16        EGA, VGA
  36.   SCREEN 9         639          349       16        EGA, VGA  (2)
  37.   SCREEN 10        639          349       4         EGA, VGA  (3)
  38.   SCREEN 11        639          479       2         MCGA, VGA
  39.   SCREEN 12        639          479       16        VGA
  40.   SCREEN 13        319          199       256       MCGA, VGA
  41.   VESA6A           799          599       16        (4)
  42.   XMode16      up to 799     up to 599    16        Super EGA/VGA
  43.   Super13          319          399       256       VGA
  44.   Super13a         359          479       256       VGA
  45.   SVGA16       up to 1024    up to 768    16        Super VGA
  46.   SVGA256      up to 1024    up to 768    256       Super VGA
  47.  
  48.   (1) Requires MSHERC.COM or QBHERC.COM
  49.   (2) EGA with 128k or more memory
  50.   (3) monochrome monitor only
  51.   (4) VESA6A is supported by many Super VGA cards with multi-frequency
  52.       monitors.  See ScreenMode.
  53.   (5) untested mode; should work with any subroutine which supports
  54.       SCREEN 2.  Your feedback, please!
  55.  
  56.   Registered QLIB users may use QLIB's EGAVGA.obj and NOSVGA.obj
  57.   stub files to reduce the size of their .EXE files.  QLIB's stub files
  58.   are similar to the NOEM.obj and NOCOM.obj files supplied by Microsoft
  59.   with QuickBASIC.  EGAVGA eliminates code and data required for monochrome,
  60.   CGA and InColor graphics modes, while NOSVGA eliminates code for Super VGA
  61.   modes.  You must link with the /NOE option when using these stub files.
  62.  
  63.   Example:  I want MYPROG.EXE to support only EGA or VGA 16-color modes
  64.  
  65.   compile: BC MYPROG /O;
  66.   link:    LINK /EX /NOE MYPROG+EGAVGA+NOSVGA,,,QLIB;
  67.  
  68.   linking with EGAVGA.obj reduces .EXE file size by up to 2,630 bytes;
  69.   linking with NOSVGA.obj reduces .EXE size by up to 3,152 bytes.
  70.  
  71. The style% parameter used in many QLIB Graphics subroutines follows these
  72. general rules:
  73.  
  74.     style% =  0 XORs the text/pixel/line/whatever with the pre-existing
  75.                 screen: if a pixel (x,y) is XORed to the screen, the pixel
  76.                 will be turned on if previously off, or will be turned off
  77.                 if previously on;
  78.  
  79.     style% =  1 is normal; lines are drawn, pixels are turned on, text is
  80.                 foreground-on-background, and the previous screen content
  81.                 is ignored or obliterated;
  82.  
  83.     style% =  2 similar to style% 1, but foreground color only is updated
  84.  
  85.     style% =  3 ORs the line or block with the existing screen; this means
  86.                 that the new stuff is added to the old.
  87.  
  88.     style% =  4 ANDs a block (or fillbox) with the existing screen; within
  89.                 the block's limits, only those pixels where both the
  90.                 previous screen and the pattern in the block have ON pixels
  91.                 will there be a resulting ON pixel;
  92.  
  93.     style% = -3 similar to style% 3, but reverses the foreground and
  94.                 background before combining it with the screen
  95.  
  96.     style% = -2 similar to style% 2, but reverses the foreground and
  97.                 background before combining it with the screen
  98.  
  99.     style% = -1 like style% 1, but uses background color.  In monochrome
  100.                 modes, pixels are erased, text is black with a bright
  101.                 background.
  102.  
  103.  
  104.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  105.  
  106.     Subroutine: BitBlockSave(seg%, x0%, y0%, x1%, y1%)
  107.     Subroutine: BitBlockRestore(seg%, x%, y%, style%)
  108.     object files: bitblock.obj ($graph.obj, bb02.obj, bb04.obj, bb06.obj,
  109.                                 bb08.obj, bb10.obj, bb12.obj, bb14.obj)
  110.  
  111.     Function: bytes% = BitBlockBytes(x0%, y0%, x1%, y1%)
  112.     object files: bbbytes.obj ($graph.obj)
  113.  
  114.     Modes supported: All
  115.  
  116.     BitBlockSave copies a section of the graphics screen to system memory
  117.     in order to copy the block back to the screen later with BitBlockRestore.
  118.  
  119.     BitBlockBytes returns the number of bytes of memory required store
  120.     the entire pixel block.  Bytes% = 0 if the block is too big.  After
  121.     calculating the bytes required, you may use AllocMem(bytes) to
  122.     allocate the memory space required.  See AllocMem in DATA.DOC.
  123.     Note that bit block memory requirements can be large; the huge model
  124.     library QLIBH.LIB is required for large bitblocks in 16-color and
  125.     256-color modes.
  126.  
  127.     style% values supported by BitBlockRestore are:
  128.  
  129.     SCREEN 13, super13, super13a, SVGA256:
  130.      1 = replace existing screen area with bit block
  131.      2 = replace existing screen with non-zero pixels in bit block
  132.  
  133.     HGraph (InColor):
  134.      4 = AND the bit block with the existing screen
  135.      3 = OR the bit block with the existing screen
  136.      1,2 = replace existing screen area with bit block
  137.      0 = XOR the bit block with the existing image
  138.     -1,-2 = replace existing screen area with inverse bit block
  139.  
  140.      16-color EGA/VGA-type modes including SVGA16, and SCREEN 10:
  141.       same as InColor, plus:
  142.      -3 = OR the inverse bit block with the existing screen
  143.      -4 = AND the inverse bit block with the existing screen
  144.  
  145.      SCREEN 1, 2, 3, 11, and HGraph (mono):
  146.       2 = combine non-zero pixels in the bit block with the
  147.           pre-existing image
  148.       1 = replace the existing screen image with un-altered
  149.           bit block
  150.       0 = XOR the bit block with the existing image
  151.      -1 = replace existing screen image with inverse bit block
  152.      -2 = combine non-zero pixel in the inverse bit block with
  153.           the previous screen image
  154.  
  155.     See example on next page.
  156.  
  157.     BIT BLOCK EXAMPLE:
  158.  
  159.  
  160.         REM  This example calculates the array size required,
  161.         REM  dimensions the array, saves a portion of the screen and
  162.         REM  restores it later.
  163.  
  164.         REM $INCLUDE: 'qlib.bi'
  165.         REM  start in the desired graphics mode
  166.               .
  167.               .
  168.               .
  169.         x0 = 100: y0 = 0: x1 = 400: y1 = 347
  170.         bytes% = BitBlockBytes(x0%, y0%, x1%, y1%)
  171.         REM  Note that huge model BitBlockBytes returns a LONG integer
  172.         bbseg% = AllocMem(bytes%)
  173.         CALL BitBlockSave(bbseg%, x0%, y0%, x1%, y1%)
  174.               .
  175.               .
  176.               .
  177.         REM  now we'll copy the block back to the screen
  178.         CALL BitBlockRestore(bbseg%, x2%, y2%, style%)
  179.         REM  x2% and y2% may be any coordinates on the screen
  180.         REM  also release the memory block
  181.         CALL FreeMem(bbseg%)
  182.  
  183.  
  184.     If you do not intend to support all QLIB graphics modes, you can
  185.     call mode-specific BitBlock subroutines to reduce .EXE size.
  186.     These subroutines use the same calling parameters as BitBlockSave
  187.     and BitBlockRestore:
  188.  
  189.     (save bit block)
  190.  
  191.     getbb02: SCREEN 1-4, SCREEN 11, HGraph (mono and InColor)
  192.     getbb06: SCREEN 7-10, SCREEN 12, SVGA16(0), XMODE16
  193.     getbb08: SCREEN 13
  194.     getbb10: Super13, Super13a
  195.     getbb12: SVGA16
  196.     getbb14: SVGA256
  197.  
  198.     (restore bit block)
  199.  
  200.     putbb02: SCREEN 1-4, SCREEN 11, HGraph (mono only)
  201.     putbb04: HGraph (InColor only)
  202.     putbb06: SCREEN 7-10, SCREEN 12, SVGA16(0), XMODE16
  203.     putbb08: SCREEN 13
  204.     putbb10: Super13, Super13a
  205.     putbb12: SVGA16
  206.     putbb14: SVGA256
  207.  
  208.  
  209.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  210.  
  211.     Subroutine: BitPlaneSave(seg%, x0%, y0%, x1%, y1%, plane%)
  212.     Subroutine: BitPlaneRestore(seg%, x0%, y0%, style%, plane%)
  213.     object files: same as BitBlockRestore and BitBlockSave
  214.  
  215.     Function: bytes% = BitPlaneBytes(x0%, y0%, x1%, y1%)
  216.     object files: bbbytes.obj ($graph.obj)
  217.  
  218.     Modes supported: HGraph (InColor)
  219.                      SCREEN 7,8,12
  220.                      SCREEN 9  (requires 128k+ EGA memory)
  221.                      VESA6A, XMode16
  222.                      SCREEN 10 (planes 0 and 2)
  223.  
  224.     BitPlaneSave subroutines copy a section of the graphics screen to a
  225.     memory buffer in order to copy that block back to the screen with
  226.     BitPlaneRestore.  This is similar to the BitBlockSave/BitBlockRestore
  227.     subroutines, except that BitPlane subroutines copy to or from only one
  228.     of the four "planes" of memory in 16-color modes.  This is handy when
  229.     the area you want to copy is too big to fit in one array, or when you
  230.     want to move or modify only one plane at a time.  The exact color
  231.     represented by each plane is determined by PALETTE or COLOR statements.
  232.  
  233.     BitPlaneBytes calculates the number of bytes of memory required to save
  234.     the desired portion of the plane.  All style% values work with
  235.     BitPlaneRestore.  You may use AllocMem(bytes%) to allocate memory
  236.     space for the bit plane.
  237.  
  238.     Example:
  239.          REM $INCLUDE: 'qlib.bi'
  240.          REM  calculate the array size required, allocate the memory,
  241.          REM  save a portion of one plane of the screen and restores it later.
  242.          REM  note that valid plane numbers are 0 - 3
  243.  
  244.          REM  First I need to establish graphics mode
  245.          CALL Xmode16(xmode%, maxX%, maxY%)
  246.               .
  247.               .
  248.          x0 = 100: y0 = 0: x1 = 400: y1 = 347
  249.          bytes% = BitPlaneBytes(x0%, y0%, x1%, y1%)
  250.          seg% = AllocMem(bytes%): plane% = 0
  251.          CALL BitPlaneSave(seg%, x0%, y0%, x1%, y1%, plane%)
  252.               .
  253.               .
  254.          REM  now we'll copy the plane back to the screen
  255.          CALL BitPlaneRestore(seg%, x2%, y2%, style%, plane%)
  256.  
  257.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  258.  
  259.     Subroutine: ClearView
  260.     object files: clrview.obj ($graph.obj, $horiz.obj)
  261.  
  262.     Modes supported: All
  263.  
  264.        ClearView erases everything within the active viewport.  In
  265.     color modes, the background color set by GraphColor is used.  Use
  266.     SetView to establish the active viewport.
  267.  
  268.     Example:
  269.       CALL ClearView
  270.  
  271.  
  272.  
  273.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  274.  
  275.      Function: colorvalue% = Color16(red%, green%, blue%)
  276.      object file: color16.obj
  277.  
  278.      supports EGA and VGA 16-color modes
  279.  
  280.           Color16 calculates a color value from individual red, green and
  281.      blue intensities, for changing the color palette in 16-color modes
  282.      (text or graphics).  Used with Palette16.  Red%, green% and blue%
  283.      range from 0 (off) to 3 (highest intensity).
  284.  
  285.      Example:  see Palette16
  286.  
  287.  
  288.  
  289.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  290.  
  291.      Function: colorvalue& = Color256&(red%, green%, blue%)
  292.      object file: color256.obj
  293.  
  294.      Supports all VGA and SVGA 256-color modes
  295.  
  296.           Color256& returns a LONG INTEGER color value from individual
  297.      red% green% and blue% components for changing palette colors in
  298.      256-color modes.  Color256& changes the actual color associated
  299.      with a particular color attribute.  With Color256&, red, green and
  300.      blue color intensitites may range from 0 (off) to 63 (highest intensity).
  301.  
  302.      Example:  see Palette256
  303.  
  304.  
  305.  
  306.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  307.  
  308.     Subroutine: DrawBox(x0%, y0%, x1%. y1%, style%)
  309.     object file: drawbox.obj ($graph.obj, $horiz.obj, $vert.obj)
  310.  
  311.     Modes supported: All
  312.  
  313.          DrawBox draws a box with corners at (x0%, y0%), (x0%, y1%),
  314.     (x1%, y0%), (x1%, y1%).  Legal style% parameters are -1, 0, and 1.
  315.     If any part of the box lies outside the active graphics viewport,
  316.     that part of the box will not be drawn.  See also LinePattern.
  317.  
  318.     Example:
  319.          CALL HGraph
  320.          x0% = 10: y0% = 10: x1% = 79: y1% = 38: style% = 0
  321.          CALL DrawBox(x0%, y0%, x1%, y1%, style%)
  322.  
  323.  
  324.  
  325.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  326.  
  327.     Subroutine: DrawCircle(xc%, yc%, Xradius%, style%)
  328.     Subroutine: CircleAspect(numerator%, denominator%)
  329.     object files: drawcirc.obj ($graph.obj, $putdot.obj)
  330.  
  331.     Modes supported: All
  332.  
  333.        DrawCircle draws a circle on a graphics screen centered at xc%, yc%,
  334.     with x-radius Xradius%.  The circle's aspect ratio may be changed with
  335.     CircleAspect.  Legal style% parameters are -1, 0 and 1 with monochrome
  336.     modes.  In color modes, style% parameters 2, -2, 3 and -3 are also
  337.     supported. Only the part of the circle which lies within the viewport
  338.     defined by SetView will be drawn.
  339.  
  340.     CircleAspect changes the aspect ratio of the circle; using CircleAspect,
  341.     you can make the circle look like a flattened ellipse or a tall ellipse.
  342.     CircleAspect changes the Y-dimension of the circle; the X-dimension is
  343.     controlled with Xradius%.  QLIB's default is an aspect ratio of 1:1 in
  344.     most graphics modes.  SCREEN 12 and XMode16 circles may not have a 1:1
  345.     aspect ratio.  CAUTION: extreme aspect ratios are not supported by
  346.     DrawCircle.  With numerator% = 1, a maximum usable denominator% is 5,
  347.     or else a "divide by zero" error will occur.  With denominator% = 1,
  348.     a high numerator will cause unpredictable results.
  349.  
  350.     Example:
  351.          CALL DrawCircle(xc%, yc%, Xradius%, style%)
  352.  
  353.  
  354.  
  355.  
  356.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  357.  
  358.     Subroutine: DrawLine(x0%, y0%, x1%, y1%, style%)
  359.     object files: drawline.obj ($graph.obj, $horiz.obj, $vert.obj
  360.                                 $loslope.obj, $hislope.obj)
  361.  
  362.     Modes supported: All
  363.  
  364.        DrawLine draws a line from x0%, y0% to x1%, y1%.  Legal style
  365.     parameters are -4 through 4.  See also LinePattern.
  366.  
  367.     Example:
  368.          x0% = 0: y0% = 0: x1% = 719: y1% = 348: style% = -1
  369.          CALL DrawLine(x0%, y0%, x1%, y1%, style%)
  370.          REM this erases a diagonal line across the screen
  371.  
  372.  
  373.  
  374.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  375.  
  376.    Subroutine: FillArea(x%, y%, reserved%)
  377.    object files: fillarea.obj ($graph.obj, $horiz.obj, fpattern.obj)
  378.  
  379.    Modes supported: All
  380.  
  381.          FillArea fills irregularly-shaped areas enclosed by solid lines.
  382.     FillArea works best with SIMPLE areas; holes in the area or areas with
  383.     "inside" corners dividing horizontal lines may not be filled properly.
  384.     Further development is planned, but FillArea in its present form is
  385.     useful in many circumstances.  FillArea works by starting at the seed
  386.     pixel (x%, y%) and looking left and right for non-black region boundaries,
  387.     then filling horizontal lines between the boundaries.  FillArea works
  388.     upward until the top of the area has been reached, then returns to the
  389.     seed pixel and works downward.  Reserved% is reserved for QLIB's style%
  390.     parameter.  FillArea presently assumes style% = 1.
  391.  
  392.     Example:
  393.          CALL HGraph
  394.               .
  395.               .
  396.               .
  397.          CALL GraphColor(attr%)             ' for color modes
  398.          CALL FillPattern(pattern$)         ' optional fill pattern
  399.          CALL FillArea(x%, y%, reserved%)
  400.  
  401.  
  402.  
  403.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  404.  
  405.     Subroutine: FillBox(x0%, y0%, x1%. y1%, style%)
  406.     object files: fillbox.obj ($graph.obj, $horiz.obj)
  407.  
  408.     Modes supported: All
  409.  
  410.        Similar to DrawBox, FillBox uses the same coordinates and style
  411.     variable, but fills the box instead of drawing the sides.  If
  412.     style% = 1 or 2, an optional pattern may be used to fill the box
  413.     (except SCREEN 1).  See FillPattern.
  414.  
  415.     Example:
  416.       CALL HGraph
  417.          x0% = 10: y0% = 10: x1% = 79: y1% = 38: style% = 0
  418.          CALL FillBox(x0%, y0%, x1%, y1%, style%)
  419.  
  420.  
  421.  
  422.  
  423.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  424.  
  425.     Subroutine: FillPattern(pattern$)
  426.     object files: fpattern.obj ($horiz.obj, $graph.obj)
  427.  
  428.     Modes supported: HGraph (mono annd InColor)
  429.                      VESA6A, XMode16, SVGA16
  430.                      SCREEN 2,3,7,8,9,10,11,12
  431.  
  432.         FillPattern defines an optional pattern used by FillBox if
  433.     style% >= 1,  or by FillArea (which assumes style% = 1). The bit
  434.     patterns in the first 8 characters of pattern$ are used to modify the
  435.     fill in the box or area.  FillPattern must be called before each call
  436.     to FillBox or FillArea.  See Examples.  FillBox will replace box borders.
  437.     If you want the box to have a solid outline, call DrawBox with style% = 1
  438.     after using FillBox with a pattern.  Using style% = 1, the pattern will
  439.     completely replace whatever was in the box.  16-color modes use
  440.     style% = 2.  BIT2INT in DATA.DOC is useful for establishing patterns.
  441.  
  442.     Sample patterns, and what they produce:
  443.  
  444.     pattern$ = CHR$(255) + STRING$(5,32)    ' produces a pattern of squares
  445.     pattern$ = STRING$(8,32)                ' produces vertical lines
  446.     pattern$ = CHR$(255) + STRING$(5,0)     ' produces horizontal lines
  447.  
  448.     pattern$ = STRING$(8,0): k% = 1
  449.     FOR i% = 1 TO 8
  450.          MID$(pattern$, i%) = CHR$(k%)
  451.          CALL ShiftINT(k%, 1)
  452.     NEXT i%                                 ' produces diagonal lines, from 
  453.                                             ' upper right to lower left
  454.     pattern$ = STRING$(8,0):k% = 128
  455.     FOR i% = 1 TO 8
  456.          MID$(pattern$, i%) = CHR$(k%)
  457.          CALL ShiftINT(k%, -1)
  458.     NEXT i%                                 ' produces diagonal lines, from
  459.                                             ' upper left to lower right
  460.  
  461.     Example:
  462.       x0% = 10: y0% = 10: x1% = 79: y1% = 38: style% = 1
  463.       pattern$ = CHR$(255) + STRING$(5,32)        ' pattern for squares
  464.       CALL FillPattern(pattern$)
  465.       CALL FillBox(x0%, y0%, x1%, y1%, style%)    ' fill box with pattern
  466.       CALL DrawBox(x0%, y0%, x1%, y1%, style%)    ' draw solid box outline
  467.       CALL FillArea(x%, y%, reserved%)            ' no pattern used
  468.                                                   ' because FillPattern
  469.                                                   ' was not called before
  470.                                                   ' FillArea
  471.  
  472.  
  473.  
  474.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  475.  
  476.     Subroutine: FontWidth(pixels%)
  477.     object files: fwidth.obj (f8x14.obj)
  478.  
  479.     Modes supported: All
  480.  
  481.     GPrint subroutines' default character width is 8 pixels.  FontWidth
  482.     changes the number of pixels per character, permitting compressed
  483.     or expanded GPRINTing.  When using fonts less than 8 pixels wide,
  484.     FontWidth can be used to make GPRINT to space the characters properly.
  485.  
  486.     GPRINT prints 8-pixel wide characters no matter what FontWidth is;
  487.     FontWidth changes the spacing from the left side of one character to
  488.     the left side of the next.
  489.  
  490.     Example:
  491.  
  492.     DEFINT A-Z
  493.     CALL GPrint("normal character spacing",10,10,1)
  494.     CALL FontWidth(10)
  495.     CALL GPrint(" 10-pixel character spacing",10,30,1)
  496.  
  497.  
  498.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  499.  
  500.     Subroutine: GBaseSeg (s%)
  501.     object files: gbaseseg.obj ($graph.obj)
  502.  
  503.     Modes supported: HGraph (monochrome only)
  504.                      SCREEN 1,2,3,4,11,13
  505.  
  506.     GBaseSeg re-directs QLIB's Graphics subroutines to an alternate buffer.
  507.     This may be used to duplicate the effect of multiple screen pages.
  508.     GBaseSeg works only with non-planar, non-bank switched modes.
  509.     S% is the segment base address of the alternate buffer.  QLIB assumes
  510.     that the buffer begins at the start of the segment.  If you call
  511.     GBaseSeg with s% = 0, the default video buffer becomes active again.
  512.  
  513.     Note that GBaseSeg will not work if you change graphics modes after
  514.     calling GBaseSeg.
  515.  
  516.     When operating under a multi-tasking enviornment, such as DesqView,
  517.     GBaseSeg may also work with any mode supported by the multi-task
  518.     control program.  Feedback, please!
  519.  
  520.     Example:
  521.  
  522.     REM $INCLUDE: 'qlib.bi'
  523.  
  524.     ' load existing screen image to RAM buffer
  525.         gpd = fload("screen13.gph")
  526.  
  527.     ' switch to graphics mode
  528.         SCREEN 13
  529.  
  530.     ' after switching to graphics mode, tell QLIB
  531.     ' where the off-screen buffer is
  532.         CALL gbaseseg(gpd)
  533.  
  534.     ' modify the off-screen image as desired
  535.         CALL GraphColor(10)
  536.         CALL DrawLine(0, 199, 319, 0, 1)
  537.         CALL gprint("this was printed to an off-screen buffer", 0, 60, 2)
  538.  
  539.     ' switch back to video buffer and print a message
  540.         CALL gbaseseg(0)
  541.         CALL gprint("press any key...", 0, 0, 1)
  542.         a = getkey
  543.  
  544.     ' copy the modified alternate buffer to the video buffer
  545.     ' NOTE: Video buffer address and size vary depending on graphics mode:
  546.     '
  547.     '  mode      address  size (bytes)
  548.     '
  549.     ' SCREEN 1   &HB800   16384
  550.     ' SCREEN 2   &HB800   16384
  551.     ' SCREEN 3   &HB000   32768
  552.     ' HGraph     &HB000   32768
  553.     ' SCREEN 4   &HB800   32768
  554.     ' SCREEN 11  &HA000   38400
  555.     ' SCREEN 13  &HA000   64000
  556.  
  557.         bytes& = 64000
  558.         CALL CopyMem(gpd, 0, &HA000, 0, bytes&, 0)
  559.  
  560.     ' release the alternate buffer 'cuz I'm all done with it
  561.     ' then wait for a keypress and exit
  562.         CALL freemem(gpd)
  563.         IF getkey THEN SCREEN 0
  564.         END
  565.  
  566.  
  567.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  568.  
  569.     Subroutine: GCopy(frompage%, topage%, oops%)
  570.     object files: gcopy.obj ($graph.obj)
  571.  
  572.     Modes supported: HGraph (mono and InColor)
  573.                      Super13
  574.                      SCREEN 3,7,8,9,10
  575.  
  576.         Similar to BASIC's PCOPY command, GCopy copies one page of
  577.     graphics memory to another, but returns an error flag instead of
  578.     requiring ON ERROR to trap errors.  GCopy also works with the Super13
  579.     VGA mode.  oops% = 0 if no error, or -1 if GCopy is not supported or
  580.     if either frompage% or topage% is too large.
  581.  
  582.     Example:
  583.         frompage% = 0: topage% = 1
  584.         CALL GCopy(frompage%, topage%, oops%)
  585.  
  586.  
  587.  
  588.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  589.  
  590.     Subroutine: GetDot(x%, y%, value%)
  591.        (formerly GetPixel)
  592.     object file: getdot.obj ($graph.obj, $getdot.obj)
  593.  
  594.     Modes supported: All
  595.  
  596.          Determines the color of the pixel located at (x%, y%).
  597.     Returns value% = -1 if (x%,y%) falls outside the active graphics
  598.     viewport.
  599.  
  600.     Example:
  601.          x% = 0: y% = 0
  602.          CALL GetDot(x%, y%, value%)
  603.          REM  This will determine the color of the pixel at the upper left
  604.          REM  corner of the screen.
  605.  
  606.  
  607.  
  608.  
  609.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  610.  
  611.     Subroutine: GraphColor(attr%)
  612.     object files: gcolor.obj ($graph.obj)
  613.  
  614.     Modes supported: HGraph (InColor)
  615.                      VESA6A, XMode16, Super13, Super13a, SVGA16, SVGA256
  616.                      SCREEN 1,7,8,9,10,12,13
  617.  
  618.         Sets the color attribute to be used when QLIB subroutines are
  619.     used in color modes.  Color attributes for 16-color modes may be
  620.     calculated with ColorAttr (See VIDEO.DOC).
  621.  
  622.  
  623.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  624.  
  625.     Subroutine: GCursor(x%, y%)
  626.     Subroutine: GUCursor(x%, y%)
  627.     object file: gcursor.obj ($graph.obj, $putdot.obj)
  628.  
  629.     Modes supported: All
  630.  
  631.        GCursor subroutines put a text cursor on graphics screens
  632.     at the character box with upper left coordinates at x%, y%.
  633.     GCursor and GUCursor subroutines are similar to QLIB's text-mode
  634.     CursorON and UCursorON subroutines, except that GCursor waits until
  635.     a key has been pressed before returning to QuickBASIC.  The key
  636.     pressed may be determined with QLIB's input subroutines, or with
  637.     QB's INKEY$ function.  In HGraph, SCREEN 9, 10, or 12, GCursor
  638.     subroutines work with either normal text or QLIB's small text.  To use
  639.     GCursor with text printed by BASIC, see example 2.
  640.  
  641.     Example 1:
  642.          CALL HGraph
  643.          a$ = "I want a cursor at the 'I' at the start of this line"
  644.          x% = 5: y% = 3: style% = 1
  645.          CALL GPrint(a$, x%, y%, style%)
  646.          CALL GCursor(x%, y%)
  647.  
  648.     Example 2:
  649.          SCREEN 3                           ' uses QBHERC.COM or MSHERC.COM
  650.          CALL StdText                       ' make sure the BIOS data area
  651.                                             ' has been updated
  652.          row% = 10: column% = 3
  653.          LOCATE row%, column%: PRINT a$     ' use QB to print text
  654.          x% = (column% - 1) * 9             ' this example is for a
  655.          y% = (row% - 1) * 14               ' QBHERC 9x14 character box
  656.          CALL GCursor(x%, y%)
  657.  
  658.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  659.  
  660.     Subroutine: GMouse
  661.     object files: gmouse.obj (mousedat.obj, $graph.obj)
  662.  
  663.     GMouse initializes the alternate graphics mouse cursor driver.
  664.     After calling GMouse, QLIB's alternate mouse cursor may be used in
  665.     any graphics mode supported by QLIB.  This is nessesary because most
  666.     mouse drivers do not recognize modes other than those supported by
  667.     IBM-brand equipment (such as Hercules, InColor, ATT, super13, SVGA,
  668.     xmode16).
  669.  
  670.     The GMouse cursor has some limitations: it wraps around to the left
  671.     side of the screen if it gets within 13 bytes of the right edge, it
  672.     does not (yet) respond to QLIB's MouseLimit subroutine, and it must
  673.     first be hidden with HideGMouse before using MousePos.  GMouse works
  674.     with these QLIB mouse subroutines:
  675.  
  676.      MouseStatus   KeyOrButton   HideGMouse   ShowGMouse   MousePos
  677.  
  678.     Any time you change graphics modes, you must re-initialize GMouse.
  679.     Turn GMouse off with HideGMouse before you switch back to text mode.
  680.  
  681.     Example:
  682.        REM $INCLUDE: 'qlib.bi'    ; has declaration for MouseReady
  683.  
  684.       ' enter desired graphics mode before calling GMouse
  685.        svgaOK = SVGA256(3)
  686.        IF MouseReady THEN CALL GMouse: CALL ShowGMouse
  687.         .
  688.         .
  689.         .
  690.       ' move the mouse cursor to new location
  691.        CALL HideGMouse
  692.        CALL MousePos(x%, y%)
  693.        CALL ShowGMouse
  694.  
  695.  
  696.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  697.  
  698.     Subroutines: HGraph, HGraph0
  699.     object files: hgraph.obj (q$herc.obj, hmode.obj)
  700.  
  701.     Subroutine: HText
  702.     object files: hmode.obj (q$herc.obj)
  703.  
  704.     Requires Hercules (mono or InColor)
  705.  
  706.         These subroutines change modes on the Hercules graphics card,
  707.     without using QBHERC.COM.  If you use HGraph to set graphics mode,
  708.     QuickBASIC video input/output functions will not work, and you must use
  709.     HText to restore text mode.  QB2/QB3/QB87 users MUST use HGraph to use
  710.     Hercules graphics.  HText resets the active page to 0.  (See UseTPage in
  711.     VIDEO.DOC).  HGraph clears the entire video buffer; HGraph0 clears only
  712.     page 0.
  713.  
  714.     With HGraph0, anything in graph page 1 is undisturbed.  A graph may
  715.     be stored in page 1, the system can be switched back to text mode for a
  716.     while, and if text page 8 - 15 are not used, the graph may be restored
  717.     by calling HGraph0 and GCopy(1, 0, oops%).
  718.  
  719.     HGraph0 can also be used if text screens are stored in pages 8 - 15.
  720.     As long as graph page 1 is not used, the text screens will not be
  721.     disturbed and can be restored with HText and TCopy.
  722.  
  723.     If you are using Hercules graphics in a 2-monitor system, use HGraph0.
  724.     HGraph0 and HText will make the Monochrome monitor the default; to
  725.     use the color monitor, call ModeColor (See VIDEO.DOC).
  726.  
  727.     Example:
  728.          CALL HGraph         ' establishes Hercules Graphics mode
  729.                              ' QLIB graphics subroutines will work properly
  730.          CALL HText          ' returns Hercules system to text mode
  731.  
  732.  
  733.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  734.  
  735.     Subroutine: GCenter(st$, y%, style%)
  736.     object files: gcenter.obj ($graph.obj, gprint.obj, $gp.obj, f8x14.obj)
  737.  
  738.     GCenter prints text on a graphics screen, centered horizontally.
  739.     This subroutine calculates the correct x-coordinate, then calls
  740.     GPrint.  GCenter supports all style% parameters and graphics
  741.     modes supported by GPrint.
  742.  
  743.     Example:
  744.         REM  I want to center a graph title at the top of the screen
  745.         y% = 0                   ' top of screen
  746.         style% = 1: title$ = "Graph Title"
  747.         CALL GCenter(title$, y%, style%)
  748.  
  749.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  750.  
  751.     Subroutine: GCenterX(st$, y%, style%)
  752.     object files: gcenterx.obj ($graph.obj, gprintx.obj, $gp.obj, f8x14.obj)
  753.  
  754.     GCenterX prints double-width text on a graphics screen, centered
  755.     horizontally.  This subroutine calculates the correct x-coordinate,
  756.     then calls GPrintX.  GCenterX supports all style% parameters and
  757.     graphics modes supported by GPrintX.
  758.  
  759.     Example:
  760.         REM  I want to center a graph title at the top of the screen
  761.         y% = 0                   ' top of screen
  762.         style% = 1
  763.         title$ = "Graph Title"
  764.         CALL GCenterX(title$, y%, style%)
  765.  
  766.  
  767.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  768.  
  769.     Subroutine: GLineEdit(st$, x%, y%, style%, options%, keycode%)
  770.     object files: gedit.obj (q$edit.obj, gcursor.obj, gprint.obj)
  771.  
  772.     Modes supported: All
  773.  
  774.       GLineEdit works like LineEdit (see INPUT.DOC), but is usable in
  775.     graphics modes.  GLineEdit uses all LineEdit options except 8 (BIOS
  776.     display) and -32768 (alternate cursor).  All LineEdit editing commands,
  777.     as well as StartEdit and LastEdit, work properly with GLineEdit.
  778.     GLineEdit also works fine with SmallText.  See LineEdit for examples.
  779.     Style% 1 and -1 work best.
  780.  
  781.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  782.  
  783.     Subroutine: GLoad(filename$, oops%)
  784.     Subroutine: GSave(filename$, oops%)
  785.     object files: gsave.obj ($graph.obj, $asciiz.obj)
  786.  
  787.     Modes supported: HGraph (mono and InColor)
  788.                      VESA6A, XMode16, Super13, Super13a
  789.                      SCREEN 1,2,3,7,8,12,13
  790.                      SCREEN 9,10 (requires 128k+ EGA memory)
  791.  
  792.        GLoad loads a Graphics screen from a file to the screen.  The file
  793.     must have been previously saved by GSave.  GLoad and GSave load to or
  794.     save from the active graphics page.  If no error occurred, oops% = 0.
  795.     Oops% will be an MS-DOS error code if a file handling error occurs.
  796.     See the introductory remarks in DISK.DOC for MS-DOS error codes.
  797.  
  798.     NOTE: files created by GSave eat lots of disk space:
  799.  
  800.          HGraph  (mono)      32,768 bytes
  801.          HGraph  (InColor)  131,072 bytes
  802.          Super13            128,000 bytes
  803.          Super13a           172,800 bytes
  804.          VESA6A             240,000 bytes
  805.          XMode16      up to 240,000 bytes
  806.          SCREEN 1            16,384 bytes
  807.          SCREEN 2            16,384 bytes
  808.          SCREEN 7            32,000 bytes
  809.          SCREEN 8            64,000 bytes
  810.          SCREEN 9           112,000 bytes
  811.          SCREEN 10           56,000 bytes
  812.          SCREEN 11           38,400 bytes
  813.          SCREEN 12          153,600 bytes
  814.          SCREEN 13           64,000 bytes
  815.  
  816.     Example:
  817.         filename$ = "BARGRAPH.HGC"
  818.         CALL GSave(filename$, oops%)
  819.  
  820.  
  821.  
  822.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  823.  
  824.     Subroutine: GPage(page%, oops%)
  825.     object files: gpage.obj ($graph.obj, q$herc.obj)
  826.  
  827.     Modes supported: HGraph (mono and InColor)
  828.                      Super13
  829.                      SCREEN 7,8
  830.                      SCREEN 9,10    (256k EGA memory)
  831.  
  832.         GPage combines the function of UseGPage and ShowGPage; see UseGPage
  833.     and ShowGPage for further information.
  834.  
  835.     Example:
  836.         CALL GPage(page%, oops%)
  837.         REM this is equivalent to
  838.         REM  CALL UseGPage(page%, oops%)
  839.         REM  CALL ShowGPage(page%, oops%)
  840.  
  841.  
  842.  
  843.  
  844.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  845.  
  846.     Subroutine: GPrint(st$, x%, y%, style%)
  847.     object files: gprint.obj ($graph.obj, $gp.obj, f8x14.obj)
  848.  
  849.     Modes supported: HGraph (mono amd InColor)
  850.                      VESA6A, XMode16, SVGA16
  851.                      Super13, Super13a SVGA256 (no style% 0)
  852.                      SCREEN 1  (style% 1 and -1 only)
  853.                      SCREEN 2,3,7,8,9,10,11,12,13
  854.  
  855.     GPrint offers much more flexibility than BASIC's PRINT command when
  856.     printing text on a graphics screen, and it's the only way to put text
  857.     on a Hercules graphics screen if MSHERC is not loaded.  GPrint prints
  858.     a string of text anywhere on the screen in normal, reverse video, XOR
  859.     or "foreground only" modes.  GPrint is also much faster than QB's PRINT
  860.     command in graphics modes.
  861.  
  862.     The size of each character and the number of characters across the
  863.     screen depends on the graphics mode:
  864.  
  865.     mode              standard character size    columns
  866.  
  867.     HGraph & SCREEN 3     8 x 14                    90
  868.     SCREEN 1, 7, 13       8 x 8                     40
  869.     SCREEN 2, 8           8 x 8                     80
  870.     SCREEN 9,10,11,12     8 x 14                    80
  871.     Super13               8 x 14                    40
  872.     Super13a              8 x 14                    45
  873.     VESA6A, SVGA16(0)     8 x 14                   100
  874.     XMode16               8 x 14                  varies
  875.     SVGA16(1), SVGA256(3) 8 x 14                   128
  876.     SVGA256(0 or 1)       8 x 14                    80
  877.     SVGA256(2)            8 x 14                   100
  878.  
  879.     All ASCII characters may be used.  x% and y% are the PIXEL locations of
  880.     the upper left corner of the first character.  SmallText, below, allows
  881.     GPrint to use the smaller 8 x 8 character in Hercules, VESA6A, XMode16,
  882.     SCREEN 9-12 and SVGA modes.  Legal style% values are -2, -1, 0, 1 and 2.
  883.  
  884.     In modes with 8 x 8 characters, you must call SmallText sometime
  885.     before calling GPrint if you use characters greater than CHR$(127).
  886.  
  887.     To calculate how many rows of text a graphics screen can display,
  888.     divide maximum Y by pixel rows (i.e., a Hercules screen can display
  889.     347/8 = 43 rows of text in SmallText mode).
  890.  
  891.     Example:
  892.       st$ = "This is an example of text in graphics mode"
  893.       x% = 10: y% = 20: CALL GPrint(st$, x%, y%, style%)
  894.  
  895.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  896.  
  897.     Subroutine: GPrintDOWN(st$, x%, y%, style%)
  898.     Subroutine: GPrintUP(st$, x%, y%, style%)
  899.     object files: gprint.obj (q$graph.obj, $gp.obj, f8x14.obj)
  900.  
  901.     Modes supported: same as GPrint
  902.  
  903.     GPrintUP rotates the string so that text reads from the bottom of
  904.     the screen to the top.  This is useful for labeling the vertical axis of
  905.     a graph, among other things.  GPrintDOWN reads from the top of the
  906.     screen to the bottom.  These subroutines use SmallText's 8 x 8 character
  907.     box, allowing up to 43 characters from the bottom of the screen to the
  908.     top in Hercules mode.  If you are going to use characters greater than
  909.     CHR$(127), you must call SmallText some time in your program before
  910.     calling GPrintDOWN/UP.  However, QLIB does not need to be in SmallText
  911.     mode when you call GPrintDOWN or GPrintUP.    All GPrint style% values are
  912.     valid.
  913.  
  914.     Example:
  915.          DEFINT a - z
  916.          CALL HGraph
  917.          CALL SmallText             ' let GPrintUP know where to find
  918.              .                      ' character definitions > CHR$(127)
  919.              .
  920.              .
  921.          CALL GPrintUP(text$, x%, y%, style%)
  922.  
  923.  
  924.  
  925.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  926.  
  927.     Subroutine: GPrintX(st$, x%, y%, style%)
  928.     Subroutine: GPrint2X(st$, x%, y%, style%)
  929.     Subroutine: GPrintDOWNX(st$, x%, y%, style%)
  930.     Subroutine: GPrintDOWN2X(st$, x%, y%, style%)
  931.     Subroutine: GPrintUPX(st$, x%, y%, style%)
  932.     Subroutine: GPrintUP2X(st$, x%, y%, style%)
  933.     object files: gprintx.obj (q$graph.obj, $gp.obj, f8x8.obj)
  934.  
  935.     Modes supported: same as GPrint
  936.  
  937.        GPrintX subroutines are similar to GPrint, GPrintUP and GPrintDOWN,
  938.     except each character in st$ is expanded to twice its normal horizontal
  939.     size before printing it on the screen; this is handy for graph headings.
  940.     GPrint2X subroutines expand each character horizontally and vertically;
  941.     All graphics modes and styles supported by GPrint work fine with these
  942.     expanded character subroutines.  See GPrint for example.
  943.  
  944.  
  945.  
  946.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  947.  
  948.     Subroutine: LinePattern(pattern$)
  949.     object files: fpattern.obj (drawline.obj)
  950.  
  951.        LinePattern passes a string of characters of up to 8 bytes to QLIB's
  952.     DrawLine and DrawBox subroutines.  The pattern of bits in pattern$ modify
  953.     lines so that they are drawn as a series of dots and/or dashes instead of
  954.     as a solid line.  Lines drawn with a pattern will be slower than those
  955.     drawn without a pattern.  In order to use pattern$, style% must be greater
  956.     than zero. On monochrome screens, only style% 1 and 2 are useful.
  957.     LinePattern must be called before each call to DrawLine or DrawBox if
  958.     it is to work.
  959.  
  960.     Modes supported: All
  961.  
  962.      Style% parameters have the following effects:
  963.  
  964.           style% 1 = both foreground and background colors are
  965.                   drawn, obliterating underlying pixels
  966.           style% 2 = foreground only replaces pre-existing pixels.
  967.           style% 3 = foreground is ORed with pre-existing pixels
  968.           style% 4 = foreground is ANDed with pre-existing pixels.
  969.  
  970.     Example:
  971.      pattern$ = SPACE$(8)
  972.      CALL LinePattern(pattern$)
  973.      CALL DrawBox(x0, y0, x1, y1, style%)
  974.  
  975.  
  976.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  977.  
  978.     Subroutine: ScreenMode(mode%)
  979.     object files: scrmode.obj (hgraph.obj, hmode.obj)
  980.  
  981.     ScreenMode allows graphics or text mode to be set, bypassing
  982.     QuickBASIC's SCREEN command.  If your program uses QLIB's graphics
  983.     subroutines instead of QuickBASIC's graphics commands, you can reduce
  984.     your program's size significantly by using ScreenMode instead of
  985.     SCREEN.  ScreenMode also allows you to use VESA mode &H6A, which
  986.     is supported by QLIB's graphics (or use SVGA16 for high-resolution
  987.     16-color modes).
  988.  
  989.     The mode% parameter is the BIOS mode number for the screen mode
  990.     (except Hercules - QLIB uses the Microsoft convention of mode 8
  991.     for Hercules since no BIOS mode number exists for Hercules).
  992.  
  993.     BIOS mode numbers and the equivalent QuickBASIC SCREEN numbers are:
  994.  
  995.          BIOS number      equipment             SCREEN number
  996.  
  997.            &H3            CGA, MCGA, EGA, VGA   SCREEN 0 (text mode)
  998.            &H4            CGA, MCGA, EGA, VGA   SCREEN 1
  999.            &H5            CGA, MCGA, EGA, VGA   SCREEN 1
  1000.            &H6            CGA, MCGA, EGA, VGA   SCREEN 2
  1001.            &H7            Monochrome, Hercules  SCREEN 0 (text mode)
  1002.                           EGA Monochrome
  1003.            &H8            Hercules, InColor     SCREEN 3
  1004.                                                 (requires MSHERC.COM)
  1005.            &H40           ATT 6300              SCREEN 4
  1006.            &HD            EGA, VGA              SCREEN 7
  1007.            &HE            EGA, VGA              SCREEN 8
  1008.            &HF            EGA, VGA (monochrome) SCREEN 10   128k+ memory
  1009.            &H10           EGA, VGA              SCREEN 9    128k+ memory
  1010.            &H11           MCGA, VGA             SCREEN 11
  1011.            &H12           VGA                   SCREEN 12
  1012.            &H13           MCGA, VGA             SCREEN 13
  1013.            &H6A           VESA VGA
  1014.  
  1015.     NOTE: ScreenMode is NOT intended for switching between a color
  1016.     monitor and a monochrome monitor.  Use ModeColor and ModeMono for
  1017.     monitor switching.   
  1018.  
  1019.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1020.  
  1021.      Subroutine: Palette16(attribute%, colorvalue%)
  1022.      object file: palet16.obj
  1023.  
  1024.      supports: EGA and VGA 16-color modes
  1025.  
  1026.           Palette16 changes the actual color associated with a particular
  1027.      color attribute.  If you call Palette16 with attribute% and
  1028.      colorvalue% both equal to -1, the default colors will be restored.
  1029.      Palette16 works in EGA and VGA 16-color modes, except where an EGA
  1030.      card is driving a CGA monitor.  See also Color16.
  1031.  
  1032.      Example:
  1033.           REM $INCLUDE: 'qlib.bi'
  1034.           REM  I want to use a color with low-intensity red
  1035.           REM  and high-intensity blue
  1036.           red% = 1: blue% = 3: green% = 0
  1037.           colorvalue% = Color16(red%, green%, blue%)
  1038.           REM  I'll use color attribute 8 for this color
  1039.           CALL Palette16(8, colorvalue%)
  1040.  
  1041.  
  1042.  
  1043.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1044.  
  1045.      Subroutine: Palette256(attribute%, colorvalue&)
  1046.      object file: palet256.obj
  1047.  
  1048.      supports: 256-color modes
  1049.  
  1050.           Similar to Palette16, Palette256 changes the actual color
  1051.      displayed by a specified color attribute.  Colorvalue& may be
  1052.      calculated from individual red, green and blue intensities using
  1053.      Color256.
  1054.  
  1055.      Example:
  1056.           REM $INCLUDE: 'qlib.bi'
  1057.  
  1058.           red% = 63               ' brightest red
  1059.           green% = 10             ' not much green
  1060.           blue% = 32              ' medium blue intensity
  1061.  
  1062.           colorvalue& = Color256(red%, green%, blue%)
  1063.           REM  I'll use color attribute 48 for this color
  1064.           CALL Palette256(48, colorvalue%)
  1065.  
  1066.  
  1067.  
  1068.  
  1069.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1070.  
  1071.     Subroutine: PutDot(x%, y%, style%)
  1072.       (formerly SetPixel)
  1073.     object files: putdot.obj ($graph.obj, $putdot.obj, $herc16,obj,
  1074.                               $ega16.obj, $vga256.obj)
  1075.  
  1076.     Modes supported: All
  1077.  
  1078.          Sets the pixel at (x%, y%) according to the specified style% and
  1079.     current GraphColor.  In monochrome modes, legal style% values are
  1080.     -1, 0, and 1.  Color modes may use style% -4 through 4.  Coordinates
  1081.     outside the active graphics viewport are ignored.
  1082.  
  1083.     Example:
  1084.          x% = 10: y% = 10: style% = 0
  1085.          CALL PutDot(x%, y%, style%)
  1086.          REM  In this example, the pixel will be turned off if it had been
  1087.          REM  on, and will be turned on if it had been off.
  1088.  
  1089.  
  1090.  
  1091.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1092.  
  1093.     Subroutine: Restore256(s%)
  1094.     object file: save256.obj (q$alloc.obj)
  1095.  
  1096.     supports: 256-color modes
  1097.  
  1098.          Restores palette registers saved by Save256.  See Save256, below.
  1099.  
  1100.  
  1101.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1102.  
  1103.     Function: s% = Save256
  1104.     object file: save256.obj (q$alloc.obj)
  1105.  
  1106.     supports: 256-color modes
  1107.  
  1108.          Saves all color palettes in a block of RAM, so you can restore
  1109.     the color registers at a later time with Restore256.  Save256 allocates
  1110.     a block of RAM large enough to save the registers, and returns the
  1111.     segment address of the block.  After you are done with the saved
  1112.     color registers, you may release the memory block with FreeMem(s%).
  1113.  
  1114.     Example:
  1115.          REM $INCLUDE: 'qlib.bi'
  1116.          SCREEN 13
  1117.          .
  1118.          .
  1119.          .
  1120.          REM  I've changed several of the color registers and I want to
  1121.          REM  save this particular set of colors
  1122.          s% = Save256
  1123.          IF s% = 0 THEN ...       'oops- not enough RAM available
  1124.          .
  1125.          .
  1126.          .
  1127.          REM  now I want to restore this set of colors
  1128.          CALL Restore256(S%)
  1129.  
  1130.  
  1131.         
  1132.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1133.  
  1134.     Subroutine: ScreenDump(oops%)
  1135.     object files: scrndump.obj (q$graph.obj)
  1136.  
  1137.     Modes supported: HGraph (mono) not yet tested with InColor
  1138.                      SCREEN 3
  1139.  
  1140.          Prints the active graphics screen on a graphics printer (Epson MX,
  1141.     FX, RX; IBM Graphics Printer, IBM ProPrinter, and compatibles).
  1142.     ScreenDump can be stopped with the ESC key.  If this occurs, oops% = 27
  1143.     is returned (27 is the ASCII character code for the ESC key).  If the
  1144.     computer is not in Hercules graphics mode, oops% = -1.  If all went
  1145.     well, oops% = 0.  Use PrinterReady (EQUIP.DOC) to see if the printer is
  1146.     ready.
  1147.  
  1148.     Example:
  1149.          CALL ScreenDump(oops%)
  1150.          oops$ = ""
  1151.          IF oops% = -1 THEN oops$ = "Not Hercules mode"
  1152.          IF oops% = 27 THEN oops$ = "Printing stopped"
  1153.          IF LEN(oops$) THEN PRINT oops$
  1154.  
  1155.  
  1156.  
  1157.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1158.  
  1159.     Subroutine: ShowGPage(gpage%, oops%)
  1160.     object files: gpage.obj ($graph.obj)
  1161.  
  1162.     Modes supported: HGraph (mono and InColor) pages 0 and 1
  1163.                             (must be default mode)
  1164.                      SCREEN 3      pages 0 and 1
  1165.                      SCREEN 7      pages 0 through 7  (depends on EGA memory)
  1166.                      SCREEN 8      pages 0 through 3  (depends on EGA memory)
  1167.                      SCREEN 9      pages 0 and 1      (256k EGA memory)
  1168.                      SCREEN 10     pages 0 and 1      (256k EGA memory)
  1169.                      Super13       pages 0 and 1
  1170.  
  1171.          ShowGPage changes the graph page visible on the screen.
  1172.     This can be handy for animation or for storing one graph while another
  1173.     is displayed.  If gpage% is too large for the default mode, oops% = -1.
  1174.     See also GPage.
  1175.  
  1176.     Example:
  1177.          CALL HGraph              ' establish Hercules graphics mode
  1178.               .                   ' HGraph calls Use64k
  1179.               .
  1180.               .                   ' display graph 0
  1181.               .
  1182.          gpage% = 1
  1183.          CALL UseGPage(gpage%, oops%)
  1184.                                   ' now put a graph in the second page
  1185.               .
  1186.               .
  1187.               .
  1188.          CALL ShowGPage(gpage%, oops%)
  1189.                                   ' let's look at graph 1 now that it's 
  1190.               .                   ' complete
  1191.               .
  1192.               .
  1193.          gpage% = 0
  1194.          CALL GPage(gpage%, oops%) ' restore default output page
  1195.                                    ' and look at graph 0
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1201.  
  1202.     Subroutine: ShowGraphPlane(plane%, oops)
  1203.     object files: gplane.obj ($graph.obj)
  1204.  
  1205.     Modes supported: VESA6A, XMode16, SVGA16
  1206.                      SCREEN 7,8,12
  1207.                      SCREEN 9  (128k or more EGA memory)
  1208.                      SCREEN 10 (planes 0 and 2, 128k or more EGA memory)
  1209.  
  1210.         EGA and VGA memory in 16-color modes is arranged in 4 parallel
  1211.     "planes".  The 16 colors available when all planes are visible result
  1212.     from a combination of the data bits in each plane at each data address.
  1213.     The planes, numbered 0, 1, 2 and 3, each control a single color.  With
  1214.     the default palette, plane 0 is blue, plane 1 is green, plane 2 is red
  1215.     and plane 3 is "intensity".  A pixel that appears bright blue in the
  1216.     screen represents pixels at identical locations in the Blue and Intensity
  1217.     planes.  (Note that the actual colors each plane represents may change
  1218.     depending on the use of QuickBASIC's COLOR and PALETTE statements).
  1219.  
  1220.     The plane% parameters are:
  1221.  
  1222.     plane 0    plane% = 1
  1223.     plane 1    plane% = 2
  1224.     plane 2    plane% = 4
  1225.     plane 3    plane% = 8
  1226.  
  1227.     Use BASIC's OR operator to show more than one plane; i.e., to
  1228.     show only planes 0 and 3, plane% = 1 OR 8.  To restore normal output,
  1229.     plane% = 1 OR 2 OR 4 OR 8.
  1230.  
  1231.     Example:
  1232.         CALL ShowGraphPlane(plane%, oops)
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1238.  
  1239.     Subroutine: SetView(x0%, y0%, x1%, y1%)
  1240.     Subroutine: GetView(x0%, y0%, x1%, y1%)
  1241.     object files: view.obj ($graph.obj)
  1242.  
  1243.     Modes supported: All
  1244.  
  1245.          SetView establishes the active viewport on the active graphics
  1246.     page.  Most QLIB graphics subroutines limit their output to the
  1247.     active viewport.  GetView returns the viewport coordinates
  1248.     presently active.  QLIB's default viewport is the entire graphics
  1249.     screen.  If SetView is called with coordinates outside legal bounds
  1250.     (for example, if x1% = 1000), SetView limits the coordinates to the
  1251.     bounds for the active graphics mode (or to Hercules bounds if the
  1252.     system is either not in graphics mode or in an unsupported mode).
  1253.     This is NOT like QuickBASIC, which calls the out-of-bounds coordinate
  1254.     an illegal function call.  This SetView feature is handy for clearing
  1255.     out old view data or for establishing the entire screen as the
  1256.     viewport when the exact limits are variable or unknown (such as
  1257.     with XMode16).
  1258.  
  1259.     Example:
  1260.          CALL SetView(x0%, y0%, x1%, y1%)
  1261.  
  1262.  
  1263.  
  1264.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1265.  
  1266.     Subroutine: SmallText
  1267.     Subroutine: StdText
  1268.     object files: smalltxt.obj (gprint.obj, q$graph.obj, f8x8.obj)
  1269.  
  1270.     Modes supported: HGraph (mono and InColor)
  1271.                      VESA6A, XMode16, SVGA16, SVGA256
  1272.                      SCREEN 3,9,10,12
  1273.  
  1274.     GPrint and GLineEdit may be set to use a smaller 8 x 8 character,
  1275.     which allows up to 43 rows of text in Hercules graphics mode, where
  1276.     StdText (QLIB's default) results in a maximum 25 rows of text.  Once
  1277.     SmallText is called, GPrint and GLineEdit will print 8 x 8 text until
  1278.     the 8 x 14 character is restored with StdText.  8x8 and 8x14 text
  1279.     may be mixed on one screen.
  1280.  
  1281.     Example:
  1282.          CALL HGraph               ' establish Hercules graphics mode
  1283.          CALL SmallText            ' sets GPrint to use small text
  1284.          CALL GPrint(a$, x0%, y0%, style%)
  1285.  
  1286.  
  1287.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1288.  
  1289.     Subroutine: Super13
  1290.     object files: super13.obj ($graph.obj)
  1291.  
  1292.     Requires VGA
  1293.  
  1294.          This subroutine changes VGA cards to an undocumented 320 x 400
  1295.     256-color mode.  I have used this mode on PS/2 computers and with a
  1296.     variety of other VGA cards; it should be compatible with most VGA
  1297.     systems.  This mode has twice the resolution of SCREEN 13, and QLIB
  1298.     supports 2 pages in this mode.
  1299.  
  1300.     Example:
  1301.        CALL GetCRT(crt)
  1302.        IF crt = 3 THEN
  1303.            CALL Super13
  1304.            ELSE
  1305.            PRINT "Mode Super13 not available"
  1306.        END IF
  1307.           .
  1308.           .
  1309.           .
  1310.        REM  all done with graphics, go back to text mode
  1311.        CALL ModeColor               ' 80 x 25 text mode
  1312.        CALL XModeClear              ' clear QLIB's internal flags
  1313.  
  1314.  
  1315.  
  1316.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1317.  
  1318.     Subroutine: Super13a
  1319.     object file: super13a.obj ($graph.obj)
  1320.  
  1321.     Requires VGA
  1322.  
  1323.          As with Super13 above, Super13a is an undocumented 256-color
  1324.     mode which I have used on PS/2 computers and with Paradise and Oak
  1325.     Technology VGA cards.  Super13a provides 360 x 480 resolution, 270% more
  1326.     pixels than the standard SCREEN 13.  This mode does not allow multiple
  1327.     pages.  See Super13 for example.  Super13a is based on John Bridges'
  1328.     public domain mode set code and parameters.
  1329.  
  1330.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1331.  
  1332.     Function: goodmode% = SVGA16(i%)
  1333.     object file: svga16.obj (banks.obj)
  1334.  
  1335.     SVGA16 sets most super VGA boards in either a 1024x768 16-color mode
  1336.     (i% = 1) or an 800x600 16-color mode (i% = 0).  Boards supported are:
  1337.  
  1338.     Ahead Technologies
  1339.     ATI
  1340.     Chips & Technologies
  1341.     Everex
  1342.     Genoa GVGA
  1343.     NCR
  1344.     Oak Technologies
  1345.     Paradise (Western Digital)
  1346.     Trident
  1347.     Trident 8900
  1348.     Tseng (Genoa, Orchid, Willow)
  1349.     Tseng 4000
  1350.     VESA standard  (800x600 only)
  1351.     Video 7
  1352.  
  1353.     !! DO NOT USE ANY I% VALUES OTHER THAN 0 & 1 !!
  1354.  
  1355.     SVGA16() returns goodmode = 0 if the requested mode is not available
  1356.     on your equipment, goodmode <> 0 if successful.
  1357.  
  1358.     Most QLIB subroutines may be used with SVGA16 modes.  See documentation
  1359.     for each subroutine.
  1360.  
  1361.     QLIB's SVGA subroutines are derived from John Bridges' public domain
  1362.     VGAKIT board identification and bank switching code.
  1363.  
  1364.     Example:
  1365.        REM $INCLUDE: 'qlib.bi'       ' has function declaration for SVGA16()
  1366.  
  1367.        REM  Use SVGA mode if available, mode &H12 otherwise
  1368.        IF NOT SVGA16(1) THEN CALL ScreenMode(&H12)
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1374.  
  1375.     Function: goodmode% = SVGA256(i%)
  1376.     object file: svga256.obj (banks.obj)    
  1377.  
  1378.     SVGA256 is similar to SVGA16, but sets one of several 256-color modes.
  1379.     Modes available are:
  1380.  
  1381.     i% = 3:   1024x768
  1382.     i% = 2:    800x600
  1383.     i% = 1:    640x480
  1384.     i% = 0:    640x400
  1385.  
  1386.     Equipment supported is listed under SVGA16, plus:
  1387.  
  1388.     Compaq (640x480 only)
  1389.  
  1390.     !! DO NOT USE ANY I% VALUES OTHER THAN 0, 1, 2 & 3 !!
  1391.  
  1392.     SVGA256() returns goodmode = 0 if the requested mode is not available
  1393.     on your equipment, goodmode <> 0 if successful.
  1394.  
  1395.     Most QLIB subroutines may be used with SVGA16 modes.  See documentation
  1396.     for each subroutine.
  1397.  
  1398.     QLIB's SVGA subroutines are derived from John Bridges' public domain
  1399.     VGAKIT board identification and bank switching code.
  1400.  
  1401.  
  1402.     Example:
  1403.        REM $INCLUDE: 'qlib.bi'       ' has function declaration for SVGA256()
  1404.  
  1405.        REM  Use SVGA mode if available, Super13a mode otherwise
  1406.        IF NOT SVGA256(3) THEN CALL Super13a
  1407.  
  1408.  
  1409.  
  1410.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1411.  
  1412.     Subroutine: Use32k
  1413.     Subroutine: Use64k
  1414.     object file: q$herc.obj
  1415.  
  1416.     Requires Hercules (mono or InColor)
  1417.  
  1418.          Use32k masks the second 32k block of Hercules memory out of the
  1419.     memory map.  If the second 32k is included in the memory map, QLIB's
  1420.     video routines can use all Hercules screen pages.  The second 32k of
  1421.     Hercules video memory conflicts with most color monitors' address space,
  1422.     so Use32k should be used to mask the second 32k out of the memory map
  1423.     for two-monitor systems.  Use64k allows the second block.  QLIB's
  1424.     default is Use32k.   You MUST call Use64k if you want to use graphics
  1425.     page 1 with Hercules systems.
  1426.  
  1427.     Example:
  1428.          CALL GetCRT(crt%)
  1429.          IF crt% >= 128 THEN CALL Use64k
  1430.  
  1431.  
  1432.  
  1433.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1434.  
  1435.     Subroutine: UseFont (fseg%, fptr%, points%, bytes%)
  1436.     object files: usefont.obj, f8x14.obj
  1437.  
  1438.     Supports: all graphics modes with ymax% > 200
  1439.  
  1440.     UseFont permits use of non-standard fonts with GPrint, GPrintX, GCenter
  1441.     and GCenterX.  The font you wish to use must be somewhere in memory,
  1442.     either "hardwired" into your program or loaded from a disk file.
  1443.  
  1444.     Parameters used when calling UseFont are:
  1445.  
  1446.     fseg% = segment address of character definition data
  1447.     fptr% = offset address of character definition data
  1448.     points% = height of each character on screen (in pixel rows)
  1449.     bytes% = byte interval from the start of one character definition
  1450.              to the next
  1451.  
  1452.     QLIB's GPrint subroutines assume that each character in the font is
  1453.     8 pixels wide.
  1454.     To use character widths other than 8 pixels, use FontWidth.
  1455.     This can be used not only to print properly spaced characters in a
  1456.     font less than 8 bits wide, but may also be used to add extra space
  1457.     between characters in a string.  Note that the character definition
  1458.     data still needs to be 8 bits wide; FontWith's pixel width parameter
  1459.     tells GPRINT how much space to leave between characters.
  1460.  
  1461.     Example:
  1462.       REM $INCLUDE: 'C:\QB4\QLIB.BI'
  1463.       REM   I want to use the italic font supplied by Hercules with the
  1464.       REM   InColor Card and Graphics Card Plus.  All Hercules font files
  1465.       REM   have a byte interval of 16, even for those fonts which are
  1466.       REM   less than 16 points high.
  1467.  
  1468.       filename$ = "C:\RAMFONT\ITALICS.FNT"
  1469.       fseg% = FLoad (filename$)       ' load font file into far memory
  1470.       fptr% = 0                       ' Hercules font definitions begin
  1471.                                       ' at the start of the file
  1472.       points% = 14: bytes% = 16       ' 14-point font
  1473.       CALL UseFont (fseg%, fptr%, points%, bytes%)
  1474.       CALL FontWidth(10)              ' add extra space
  1475.  
  1476.       REM  GPrint will now use italics font until SmallText or StdText is
  1477.       REM  is called, or until UseFont is called with another font definition
  1478.       REM  Once you are done with the font, release the far memory with
  1479.       REM  CALL  FreeMem (fseg%)
  1480.  
  1481.   
  1482.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1483.  
  1484.     Subroutine: UseHercules
  1485.     Subroutine: UseDefault
  1486.     object file: q$graph.obj
  1487.  
  1488.       UseHercules forces QLIB's graphics subroutines to use Hercules-
  1489.     mode algorithms.  This is handy when you want to create a virtual
  1490.     graphics screen (for ScreenDump, as an example) while the computer
  1491.     is displaying a graph in another graphics mode.  UseDefault causes
  1492.     QLIB to use the algorithms for the system's active graphics mode.
  1493.     UseHercules is NOT required if the system is in Hercules mode.
  1494.  
  1495.     Example:
  1496.       CALL UseHercules
  1497.           .
  1498.           .
  1499.           .
  1500.       CALL UseDefault
  1501.  
  1502.  
  1503.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1504.  
  1505.     Subroutine: UseGPage(gpage%, oops%)
  1506.     object files: gpage.obj ($graph.obj)
  1507.  
  1508.     Modes supported: HGraph (mono and InColor)    pages 0 and 1
  1509.                      SCREEN 3         pages 0 and 1
  1510.                      SCREEN 7         pages 0 through 7  (with 265k EGA)
  1511.                      SCREEN 8         pages 0 through 3  (with 265k EGA)
  1512.                      SCREEN 9         pages 0 and 1      (256k EGA memory)
  1513.                      SCREEN 10        pages 0 and 1      (256k EGA memory)
  1514.                      Super13          pages 0 and 1
  1515.  
  1516.          UseGPage changes the default screen page for QLIB's graphics
  1517.     subroutines.  QLIB's default gpage% is 0.  If multiple pages are not
  1518.     available for the current mode, or gpage% is too big, oops% = -1.
  1519.  
  1520.     Example:
  1521.          CALL HGraph              ' establish Hercules graphics mode
  1522.                                   ' HGraph calls Use64k
  1523.          gpage% = 1
  1524.          CALL UseGPage(gpage%, oops%)
  1525.                                   ' QLIB's graphics subroutines use page 1 now
  1526.  
  1527.  
  1528.  
  1529.  
  1530.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1531.  
  1532.     Function: goodboard = WhichVGA
  1533.     object file: banks.obj
  1534.  
  1535.     WhichVGA identifies supported video boards and sets up the VGAKIT
  1536.     software for the equipment installed.  Goodboard = 0 if a supported
  1537.     board is not installed, or goodboard <> 0 if a VGAKIT-compatible
  1538.     SVGA is installed.
  1539.  
  1540.     You do not need to call WhichVGA before call SVGA16() or SVGA256().
  1541.  
  1542.     Example:
  1543.  
  1544.     DEFINT A-Z
  1545.     DECLARE FUNCTION whichvga ()
  1546.     DECLARE FUNCTION svga256 (i%)
  1547.         IF whichvga THEN
  1548.             svga = svga256(3)
  1549.             IF svga = 0 THEN END
  1550.             CALL bprint("SVGA", 17, 12, 12)
  1551.             CALL GraphColor(12)
  1552.             CALL line256(0, 0, 1000, 1000, 1)  ' line is clipped
  1553.                                                ' at screen edge
  1554.             .
  1555.             .
  1556.             .
  1557.         ' all done with SVGA
  1558.             call modecolor
  1559.             call xmodeclear
  1560.  
  1561.  
  1562.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1563.  
  1564.     Subroutine: XMode16(m%, maxX%, maxY%)
  1565.     Subroutine: XMode16A(m0%, m1%, maxX%, maxY%)
  1566.     object file: xmode.obj ($graph.obj)
  1567.  
  1568.     Subroutine: XModeClear
  1569.     Subroutine: ModeColor
  1570.  
  1571.        XMode16 subroutines allow the use of many extended EGA and VGA
  1572.     graphics cards at higher resolutions than IBM's products allow, in
  1573.     16-color modes.  Depending on the graphics card/monitor combination
  1574.     in use, resolutions up to 800 pixels horizontal and 600 pixels vertical
  1575.     are possible.  The manual supplied with your extended EGA or VGA card
  1576.     contains the information you need to put the high-resolution modes to
  1577.     work.  A multi-frequency monitor is generally required (see the graphics
  1578.     card manual for specific requirements).
  1579.  
  1580.     You must have the required equipment and use the correct mode number;
  1581.     hardware damage may result from improper use of XMode16.  I cannot be
  1582.     held responsible for damage resulting from use of XMode16.
  1583.  
  1584.     When using XMode16, the parameters required are:
  1585.  
  1586.      m% = mode number (from graphics card manual, for 8086 register AL)
  1587.      maxX% = maximum horizontal dimension
  1588.      maxY% = maximum vertical dimension
  1589.  
  1590.     If 800 horizontal pixels are available, maxX% should be 799.  Similarly,
  1591.     if 600 vertical pixels are possible, maxY% should be 599.
  1592.  
  1593.     If your graphics card requires two mode parameters in the 8086's
  1594.     AL and BL registers, use XMode16A instead, where
  1595.  
  1596.      m0% = mode number for AL register
  1597.      m1% = mode number for BL register
  1598.      maxX% = maximum horizontal dimension
  1599.      maxY% = maximum vertical dimension
  1600.  
  1601.     Any QLIB subroutines compatible with XMode16 will work equally well
  1602.     with XMode16A.
  1603.  
  1604.     Your graphics card manual lists mode numbers, equipment requirements,
  1605.     and the number of horizontal and vertical pixels corresponding to the
  1606.     mode.  Mode numbers are usually in hex format.  Some modes and
  1607.     corresponding mode numbers are listed on the next page:
  1608.  
  1609.  
  1610.  
  1611.     Equipment            mode     mode number   Example
  1612.  
  1613.     Orchid ProDesigner   800x600     &H29       CALL XMode16(&H29, 799%, 599%)
  1614.     STB EM/16
  1615.     Genoa
  1616.     Sigma X16
  1617.  
  1618.  
  1619.     Everex MED EGA       640X480     &H70, &H00
  1620.     (Micro Enhancer Deluxe)                CALL XMode16a(&H70, &H00, 639%, 479%)
  1621.                          752x410     &H70, &H01
  1622.                                            CALL XMode16a(&H70, &H01, 751%, 409%)
  1623.  
  1624.  
  1625.     ATI VGA Wonder       800x600     &H54       CALL XMode16(&H54, 799%, 599%)
  1626.  
  1627.  
  1628.     ATI VIP              800x560     &H53       CALL XMode16(&H53, 799%, 559%)
  1629.  
  1630.  
  1631.     Paradise Plus-16     800x600     &H58       CALL XMode16(&H58, 799%, 599%)
  1632.     Paradise Professional
  1633.  
  1634.     Video 7 Fastwrite    800x600     &H62       CALL XMode16(&H62, 799%, 599%)
  1635.     Video 7 VRAM
  1636.  
  1637.     If any of this information conflicts with the specifications in your
  1638.     video card's instruction manual, the manual's recommendation is a safer
  1639.     bet.  Note that all the above modes require a multi-frequency monitor.
  1640.  
  1641.     When you're all done with Graphics mode, CALL ModeColor to return to
  1642.     80x25 text mode, and CALL XModeClear to reset QLIB's internal XMode flags.
  1643.  
  1644.  
  1645.      REM  All done with graphics for now, go back to 80 x 25 text mode
  1646.      CALL ModeColor
  1647.      REM  also clear QLIB's internal flags
  1648.      CALL XModeClear
  1649.  
  1650.   ***************** QWINDOW USER-DEFINED COORDINATE SUBSYSTEM ****************
  1651.  
  1652.  
  1653.   The QLIB QWindow user-defined coordinate subsystem for QLIB graphics is
  1654.   intended as a replacement for BASIC's WINDOW command.  The QWindow system
  1655.   permits the programmer to specify custom coordinates for any QLIB graphics
  1656.   mode, and changes the direction of increasing y-coordinates from the
  1657.   default top-to-bottom to the more familiar bottom-to-top orientation.
  1658.  
  1659.   QWindow subroutines are listed at the end of this file.
  1660.  
  1661.   For each QWindow graphics subroutine, the usage and calling parameters are
  1662.   identical to the primary QLIB graphics subroutine.  For example,
  1663.   to use QWBitBlockBytes, see the documentation for BitBlockBytes, but
  1664.   call QWBitBlockBytes with QWindow coordinates.
  1665.  
  1666.   If you have defined your own coordinates, you may still use QLIB's primary
  1667.   graphics subroutines with the absolute coordinates at the beginning of
  1668.   this file.  If your program repeatedly calls QLIB graphics subroutines
  1669.   with the same coordinates, your program will run a bit faster if you
  1670.   convert QWindow coordinates to QLIB's native absolute coordinates and
  1671.   use the non-QWindow subroutine.  See QW2Abs.
  1672.  
  1673.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1674.  
  1675.     Subroutine: QW2Abs(x, y)
  1676.     object file: qw2abs.obj, qwindow.obj
  1677.  
  1678.         QW2Abs converts QWindow coordinates to QLIB's native absolute
  1679.     coordinates.  This is handy if you will be repeatedly calling QLIB
  1680.     graphics subroutines with the same coordinates; convertng to absolute
  1681.     coordinates and calling the non-QWindow subroutine will make your
  1682.     program run a bit faster.
  1683.  
  1684.  
  1685.    
  1686.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1687.  
  1688.     Subroutine: QWindow(x0, y0, x1, y1)
  1689.     object file: qwindow.obj ($graph.obj)
  1690.  
  1691.         QWindow establishes the user-defined coordinate system.  The
  1692.     coordinate at (x0, y0) is the lower left corner of the working area
  1693.     and the coordinate at (x1, y1) is the upper right corner of the area.
  1694.     The working area can be either the entire screen or QLIB's active view
  1695.     area (see QWScreen and QWView).  If x0 is less than 0, the origin
  1696.     of the horizontal axis will be shifted right.  If y0 is less than 0,
  1697.     the origin of the vertical axis will be shifted up.
  1698.     
  1699.  
  1700.     Example:
  1701.        DEFINT A-Z
  1702.        REM  my data series has a minimum y-value of -32 and a maximum
  1703.        REM  y-value of 181, while the x-values range from -10 to 75
  1704.  
  1705.        CALL ScreenMode(&H10)                ' EGA 640x350 mode
  1706.        CALL QWScreen                        ' coordinates relative
  1707.                                             ' to entire screen
  1708.        CALL QWindow(-10, -32, 75, 181)      ' user-defined graph coordinates
  1709.        CALL QWLine(0, -32, 0, 181, 1)       ' draw vertical axis
  1710.        CALL QWLine(-10, 0, 75, 0,  1)       ' draw horizontal axis
  1711.  
  1712.        REM put dots on the screen for a X vs. Y chart
  1713.        FOR i = 0 to 100
  1714.            CALL QWPutDot(x%(i), y%(i), style%)
  1715.        NEXT i
  1716.  
  1717.  
  1718.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1719.  
  1720.     Subroutine: QWScreen
  1721.     Subroutine: QWView
  1722.     object file: qwindow.obj ($graph.obj)
  1723.  
  1724.        These subroutines allow you to define your coordinate system
  1725.     relative to the entire screen (QWScreen) or relative to QLIB's active
  1726.     View area.
  1727.  
  1728.     Example:
  1729.        DEFINT A-Z
  1730.        REM  I want to use 90% of the screen dimensions for a plot with
  1731.        REM  coordinates from -100 to +100
  1732.  
  1733.        REM  start with View equal to entire screen area
  1734.        CALL ResetView
  1735.  
  1736.        REM  next, define the coordinate system, relative to entire screen
  1737.        CALL QWindow(-100, -100, 100, 100)
  1738.        CALL QWScreen
  1739.  
  1740.        REM  now get the absolute coordinates for 90% of the screen dimensions
  1741.        x0% = -90: y0% = -90
  1742.        x1% = 90: y0% = 90
  1743.        CALL QW2Abs(x0%, y0%)       ' convert first coordinate
  1744.        CALL QW2Abs(x1%, y1%)       ' convert second coordinate
  1745.  
  1746.        REM  use absolute coordinates to set QLIB view area
  1747.        CALL SetView(x0%, y0%, x1%, y1%)
  1748.  
  1749.        REM  make QWindow coordinates relative to active view area
  1750.        CALL QWView
  1751.  
  1752.        REM  ready to go!
  1753.  
  1754.  
  1755.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1756.  
  1757.     QWindow subroutines, the comparable QLIB subroutine and QWindow
  1758.     object files are listed below:
  1759.  
  1760.     QWindow subroutine   QLIB subroutine      object file
  1761.  
  1762.     QWLine               DrawLine             qwline.obj
  1763.     QWBox                DrawBox              qwline.obj
  1764.     QWFillBox            FillBox              qwline.obj
  1765.     QWFill               FillArea             qwfill.obj
  1766.     QWGCenter            GCenter              qwcenter.obj
  1767.     QWGCenterX           GCenterX             qwcentrx.obj
  1768.     QWCircle             DrawCircle           qwcircle.obj
  1769.     QWGLineEdit          GLineEdit            qwgedit.obj
  1770.     QWGPrint             GPrint               qwgprint.obj
  1771.     QWGPrintUP           GPrintUP             qwgprint.obj
  1772.     QWGPrintDOWN         GPrintDOWN           qwgprint.obj
  1773.     QWBitBlockBytes      BitBlockBytes        qwblock.obj
  1774.     QWBitBlockSave       BitBlockSave         qwblock.obj
  1775.     QWBitBlockRestore    BitBlockRestore      qwblock.obj
  1776.     QWBitPlaneBytes      BitPlaneBytes        qwplane.obj
  1777.     QWBitPlaneSave       BitPlaneSave         qwplane.obj
  1778.     QWBitPlaneRestore    BitPlaneRestore      qwplane.obj
  1779.     QWGetDot             GetDot               qwgetdot.obj
  1780.     QWPutDot             PutDot               qwputdot.obj
  1781.     QWGPrintX            GPrintX              qwprintx.obj
  1782.     QWGPrint2X           GPrint2X             qwprintx.obj
  1783.     QWGPrintUPX          GPrintUPX            qwprintx.obj
  1784.     QWGPrintDOWNX        GPrintDOWNX          qwprintx.obj
  1785.     QWGPrintUP2X         GPrintUP2X           qwprintx.obj
  1786.     QWGPrintDOWN2X       GPrintDOWN2X         qwprintx.obj
  1787.     QWGCursor            GCursor              qwcursor.obj
  1788.     QWGUCursor           GUCursor             qwcursor.obj
  1789.  
  1790.     In all cases, QWindow subroutines are called from your BASIC program
  1791.     with the same parameters, except that screen coordinates are QWindow
  1792.     coordinates instead of QLIB's native absolute pixel locations.
  1793.  
  1794.